Function            soundex - convert a string to soundex form

  Syntax              char *soundex(char *str, char *soundexstr);

  Prototype in        stringhk.h

  Remarks             soundex() will convert a character string to
                      soundex form (phonetic complement). The soundex
                      form will always a be null terminated string 5
                      characters long. The first character of the soundex
                      form will always be the first character in str
                      (capitalized). The remaining 4 characters will be
                      '0' to '5', using the following conventions:

                           all non-alphabetic characters are ignored

                           soundex() is case independent

                           alphabetic characters are converted to a digit
                           using the following table:

                                1 = BFPV
                                2 = CGJKQRSXZ
                                3 = DT
                                4 = L
                                5 = MN
                                all others are ignored

                           run lengths of characters are ignored (i.e.
                           the 2nd 'r' in mirror)

                      Processing ends when either str is fully processed,
                      or the soundex string is 5 characters long (not
                      including the null terminator). If str is fully
                      processed, the soundex string will be padded with
                      '0' to give it a length of 5.

                      This function is based on the soundex algorithm
                      published by Nicklaus Wirth.

  Return value        returns soundexstr.

  Example             #include <stringhk.h>

                      main()
                      {
                           char *str[] = {"Billy","bill",
                                          "mirror","marred",
                                          "Borland International" };
                           char temp[30];
                           int i;

                           for (i=0; i<5; i++)
                                printf("%s = %s",str[i],
                                       soundex(str,temp);
                      }

  Program output      Billy = B4000
                      bill = B4000
                      mirror = M2200
                      marred = M2300
                      Borland International = B2453